MacWorld 1998 March

home *** CD-ROM | disk | FTP | other *** search

/ MacWorld 1998 March / Macworld (1998-03) (Disk 1).dmg / Shareware World / Utilities / Text Processing / Alpha / Help / MacPerl Help < prev next >

Wrap

Text File | 1995-07-31 | 24.9 KB | 619 lines | [TEXT/ALFA]

######################## MacPerl Support in Alpha ######################## Introduction ============ This document describes the use of the MacPerl menu in Alpha. The MacPerl menu was written to allow Alpha to act as a front end for Matthias Neeracher's standalone MacPerl application and to make it possible to "attach" Perl scripts to Alpha. It provides a number of features designed to make the use and development of Perl scripts on the Mac more convenient. These are detailed in the rest of this document (most easily navigated using the "{}" menu on the sidebar), but here's a quick overview: Editing Perl scripts... • Perl keywords and special variables are colorized in Perl mode. • The Perl 4 man page is provided as an on-line reference, available as the file "Perl Commands" in Alpha's Help menu; it has been colorized and indexed to make it easy to read and navigate. • The man page can be referenced by command-double-clicking a highlighted Perl keyword or special variable in your Perl script. • Source files mentioned in require statements can be opened by command-double-clicking as well. Running Perl Scripts... • MacPerl scripts can be run directly from Alpha - a script can be a text window in Alpha, a highlighted selection from a window, or a disk file. • You can save scripts as MacPerl droplets and runtime applications directly from Alpha. • Perl scripts that read from standard input and write to standard output may be used to process text in Alpha's text windows. Debugging Perl scripts... • When a script fails, the error messages are displayed and the script is brought up with the line that caused the error highlighted. • A flag can be set to cause scripts to run under the Perl debugger (without modifying the script). Currently, no explicit support or documentation is provided for Perl 5, but this will follow once a stable port of Perl 5 to the 68k Macintosh emerges. Instructions for obtaining the MacPerl application are given further below. Installation ============ No special installation procedure is required before using this package. However, there are a couple of things that you may need to do to configure things for your particular machine. MacPerl application and library ------------------------------- Alpha needs to know where to find your MacPerl application in order to interact with it, and will automatically prompt you to locate it if it doesn't know where it is. You can always check and/or change the path that Alpha uses by selecting the "MacPerl" entry in the "Mode:App Paths" menu. When opening "require"d source files via the command-double-click mechanism, Alpha will always look in the "lib" folder in the MacPerl application directory. To have Alpha look for library files elsewhere, you can specify an additional personal library folder, using the "MacPerl lib folder" entry in "Mode:App Paths" menu. Text Filters Setup ------------------ If you want to use Perl scripts to process Alpha text buffers (see Text Filters), you'll need to arrange that the Perl menu is visible while you're in Text mode. While in Text mode, select "Set Mode Menus…" from the "√" pop-up menu on the side-bar and command-click on "perlMenu" in the list of menus shown. The little camel icon should appear on the menu bar when you're done. The MacPerl menu contains a hierarchical submenu of preattached scripts to be used as text filters. A sample collection of such scripts is distributed with Alpha in the ":Tcl:UserCode:Text Filters:" folder. You can specify your own folder of scripts using "MacPerl Text Filters folder" entry in "Mode:App Paths" menu. Option flags There are a handful of flags you can set to modify the way Alpha and MacPerl interact while running Perl scripts. These can be set from either the MacPerl menu or the "√" pop-up menu on the side-bar. They're described in detail below. Perl Mode ========= Perl mode is entered automatically whenever you open a file with a ".pl" or ".ph" suffix; you can also invoke it explicitly using the modes menu (downward triangle) on the sidebar. Perl mode offers a number of features supporting the editting and debugging of Perl scripts: Basic language support ---------------------- • Perl keywords and special variables appear in blue in Perl mode. • A single line or a selected block of lines may be commented out by using the "Comment Line" command under the "Convert" menu. Lines are uncommented using "Uncomment Line", which appears in the "Convert" menu when the option key is held down. • Alpha will create an index of all subroutines in your Perl script when you select "Mark File" from the Marks menu on the sidebar (the "{}" button). Once created this index is saved with your file. When you open a Perl script that hasn't already been indexed, an index is automatically created. Command-double-clicking ----------------------- A simple form of hypertext help is invoked by double-clicking on certain pieces of text while the command key is held down: • The online man page can be referenced by command-double-clicking a highlighted Perl keyword or special variable in your Perl script. Most of the clickable keywords and variables will be colored blue. Special variables containing alphabetic characters, .e.g. @ARGV, are also clickable but are not colored. • Command-double-clicking on the name of the source file in a require statement will cause that file to be opened by Alpha. Alpha will look for the file in the current script's folder, in your local library folder and in the MacPerl lib folder (in that order). The local lib folder may be specified interactively by the user (see Installation). MacPerl Menu ============ Alpha's MacPerl menu allows a number of actions. These are ... MacPerl interaction ------------------- Macperl Switch to the MacPerl application. Tell Macperl... > Open In Macperl Open the current document in MacPerl. Save As Droplet Save the current document as a MacPerl droplet. Save As Droplet Save the current document as a MacPerl runtime script. Save As CGI Save the current document as a MacPerl CGI applet. A bug in the AEGizmos package makes it impossible to create CGI applets directly from Alpha at this point. You will have to open the script in MacPerl and save it from there. Open Output Window Retrieve the contents of MacPerl's main output window into a new window under Alpha. Close Output Window Close MacPerl's main output and debugger windows. Quit Force the MacPerl application to quit. Running Perl Scripts -------------------- Run The Selection Execute the selected text as a Perl script. Run The Buffer Execute the current text window as a Perl script. Save And Run Save the current window and run the saved file as a Perl script. (see Current Directory) Run A File Run a selected disk file as a Perl script. Applying Text Filter Scripts ---------------------------- Text Filters > A hierarchical menu of "preattached" scripts to use as text filters. When a script is selected from this menu, it is immediately applied to the current text window. The menu is built from the contents of a user-selected folder. The folder is chosen using the "Mode:App Paths" menu command on the main menubar or the "Text Filters Folder" command under the Macperl "Filter Options" submenu (below). Select Buffer As Filter Select one of the open text windows to use as the text filter script. Select File As Filter Select a file to use as the text filter script. Repeat Last Filter Run again the last filter that was used. If the contents of the file or buffer has changed, the new script is run. Option flags ------------ General Options > Flags that control Alpha's behavior when executing ordinary scripts (not text filters). Retrieve Output Automatically retrieve any output written to the MacPerl output window and display it in a new window under Alpha. (same as "perlGetOutput") If the mode variable "perlRecycleOutput" is set, the previous output window is overwritten. Auto Switch Switch to MacPerl while scripts are being executed. Otherwise, Alpha remains frontmost until the script finishes. (same as "perlAutoSwitch") Prompt For Args Have Alpha prompt you for command-line arguments to be passed to the script. (same as "perlPromptArgs") Use Debugger Force the script to run under the MacPerl debugger. (same as "perlUseDebug") Control is automatically switched to MacPerl when the debugger is used. Filter Options > Flags controlling the behavior of text filters mechanism. Apply To Buffer Apply the filter to the entire current text window; otherwise, only the selected text is used. (same as "perlUseBuffer") Overwrite Selection When checked, the output from the text filter script will replace the input text in the original window. Otherwise, the output is written into a new window. (same as "perlOverwrite") Text Filters Folder Select the folder from which the Text Filters menu is built. (You can also use the "Mode:App Paths" menu.) Rebuild Filter Menu Reconstruct the "Text Filters" menu from the contents of the designated "Text Filters" folder. Mode variables -------------- A more complete set of Perl option flags are also settable through the flags menu "√" on the sidebar (while you're in Perl mode). perlAutoSwitch (same as "Auto Switch" under "General Options") perlGetOutput (same as "Retrieve Output" under "General Options") perlOverwrite (same as "Overwrite Selection" under "Filter Options") perlPromptArgs (same as "Prompt For Args" under "General Options") perlUseDebug (same as "Use Debugger" under "General Options" ) perlUsebuffer (same as "Apply To Buffer" under "Filter Options") perlRecycleOutput If selected, output returned by Macperl overwrites previous output in the "* Perl Output *" window in Alpha, instead of going into a new window. There are also two mode variables that may be examined perlLastFilter Contains the location of the last text-filter script used. perlCmdlineArgs Contains the last command-line options supplied. Note these are only passed to scripts when the "Prompt for Args" option is active. Running Scripts =============== Running scripts using the MacPerl menu is pretty straightforward. You can send the current selection, the entire current buffer, or a disk file to MacPerl for execution as a Perl script; the result will be the same as if you ran the script from MacPerl itself. Here are listed some important points to remember when running Perl scripts using the MacPerl menu. Input and Output ---------------- • Except for text filter scripts, the standard input for your script is taken from the keyboard (while MacPerl is in the foreground) and standard output goes to MacPerl's output window. If you need to interact with the script while it's running, make sure that you've selected the "AutoSwitch" flag under "General Options". • To get the output from your script, select the "Retrieve Output" flag under "General Options", this will cause Alpha to copy any output to Macperl's standard output window back into Alpha after your script has completed. You can always do this manually by using the "Get Output Window" command under the "Tell Macperl…" submenu. Again, if you need to see the results while the script is running, use "AutoSwitch" to bring MacPerl to the foreground during script execution. Current Directory ----------------- For the purpose of resolving relative file references, etc., within your script, it's important to understand how the current directory of the running script (as returned by `pwd` ) is determined. • If you run a script file (using "Run A File"), then the folder containing that file is the current folder. • If you run a script from a text buffer (using "Run The Buffer" or "Run The Selection") , it is as though you ran it directly from a window in the MacPerl application, and so the current directory your script sees is the MacPerl application folder. • If you run a script from a buffer using the "Save and Run" command, then the script is first saved to disk and then executed as a script file. In this case, the current directory is that of the script file. Command-line Args ----------------- • If the menu flag "Prompt For Args" is checked, then the user is prompted for command-line arguments at the time the script is run. These will be available inside the script through the @ARGV array, as usual. They are also saved in the Perl-mode variable "perlCmdlineArgs", and become the default arguments the next time the script is executed. Error Messages -------------- • If the script fails for some reason, Alpha will read the error messages returned by MacPerl and write them back into a new text window, called "* Perl Errors *". • The script that generated the error is brought up and the first line specifically referenced in an error message is highlighted. Note that error-trapping remains active whether "Retrieve Output" is set or not. Interrupting a Script --------------------- When you run a Perl script from Alpha, Alpha will display the watch cursor and wait for the reply from Macperl before doing anything else. There may be times when this is inappropriate, for instance, if you expect the script to run for a long time or if you think the script is misbehaving for some reason. • You can always tell Alpha to stop waiting for a script to finish by hitting "Cmd-.". This does not abort the script itself; to do that you'll have to switch over to MacPerl to terminate the script there, as well. • When you interrupt a script in this way, Alpha will no longer automatically get the output or error messages from MacPerl, when and if the script does finally terminate. You can always retrieve the contents of the output window yourself using "Get Output Window" from the "Tell MacPerl…" submenu or simply by switching over to Macperl itself. There are some simple causes for a hung script. For instance, if MacPerl is configured to check for "#!" lines in scripts and yours doesn't have one, it will put up a dialog asking whether or not to procede. If you didn't switch over to MacPerl when the script was run, you have know way of knowing this, and so you and Alpha may end up just sitting there waiting. Text Filters ============ Perl is, among other things, a powerful tool for extracting and rewriting data from text files. On a Unix system, one would typically write text-processing scripts to read from "standard input" and write to "standard output", taking advantage of command-line i/o redirection to specify the actual input and output files used at any given time. On the Mac, the typical absence of a command-line interface makes it harder to use this elegant method. The MacPerl menu in Alpha makes it possible to use scripts that read from standard input and write to standard output to process text buffers in Alpha directly. Any text window can be used as standard input and standard output can either be directed back to that same window or to a newly created one. The script used may either be a disk file or yet another Alpha text window. Applying a Text Filter ---------------------- The procedure for using Perl text filters in Alpha is simple: 1. Bring the text window you want to operate on to the front and select (highlight) the text that will be the input to the script. * If the "Apply To Buffer" option is selected, then the entire text window will be used as input and any text selection is ignored. * Only complete lines are used as input. The text used will be extended to include all of the lines on which the selected text lies. 2. Select a Perl script using one of the commands, "Select Buffer As Filter", "Select File As Filter" or "Repeat Last Filter" from the Perl menu, or by choosing one of the scripts listed in the "Text Filters" submenu. * You can see the name of the last script used by examining the variable "perlLastFilter" under the "√" menu in Perl mode. This is the script that will be used if you use "Repeat Last Filter" * If the "Prompt For Args" option has been selected, you'll be given a dialog box to type in the command-line arguments for the script. 3. The output of the script is written back out, either in the place of the input text (if the "Overwrite Selection" option is selected) or into a new text window. * As always, Alpha's unlimited undo capability let's you recover if you accidently overwrite the input text when you didn't want to. * If the script halts on an error, the filter operation is aborted and any error messages are displayed in a new window. The ability to take the script itself from a text window allows simple one-time scripts to be created and applied on the fly. This can be very useful because, even with the overhead to start up MacPerl, large-scale global search-and-replace operations (hundreds of replaces) can be substantially faster in MacPerl than in Alpha. Also, you might find it easier to apply a series of regular expression substitutions using a single, short Perl script, rather than a number of separate "Find" and "Replace All" commands in Alpha. Preattached Scripts ------------------- Frequently used text filter scripts can be conveniently accessed by placing them in a folder called "Text Filters" within the MacPerl application folder. When the MacPerl menu is first created, it looks in this folder and builds a hierarchical submenu from the names of the scripts that it finds. Note that it will also create a "Text Filters" folder if one doesn't already exist. A sampling of useful :-) Perl scripts is distributed with Alpha in the folder ":Tcl:UserCode:Text Filters". Of the scripts in the sample collection, the "Text Munging" scripts ("shuffle", "sort lines", "travesty", and "wordcount") were taken from the Camel book (Programming Perl). The "s2p" script is my adaptation of the standard code that converts Unix "sed" scripts to Perl (it was modified to work without using the C preprocessor.) "Strip Mail Headers" takes e-mail files and edits out any header lines but the few that I typically care about ("From:, "Date:", etc..). "CC To BibTeX" is a script I use that takes listings from the online "Current Contents" database and rewrites them as BibTeX database entries. To try it out, select (highlight) the sample Current Contents citation below and choose "CC To BibTeX" from the "Text Filters" submenu (make sure that "Apply To Buffer" is _not_ checked before you do!) 288. VOS MH; LAMBRY JC; ROBLES SJ; YOUVAN DC; and others. FEMTOSECOND SPECTRAL EVOLUTION OF THE EXCITED STATE OF BACTERIAL REACTION CENTERS AT 10-K. PROCEEDINGS OF THE NATIONAL ACADEMY OF SCIENCES OF THE UNITED STATES OF AMERICA, 1992 JAN 15, V89 N2:613-617. Bugs, etc. ========== Comments and suggestions regarding this package are always welcome. If there's something that bothers you, or some additional capability that you'd like to see, let me know and I'll see what I can do. Bug reports and any other comments should be directed to Tom Pollard <pollard@chem.columbia.edu> Version History =============== 2.3 7/95 - Minor tweaks and code rearrangement. 2.2 6/95 - Text filters act only on current line if "Apply to Buffer" is false and no text has been selected. More verbose commentary when running scripts. Bug fix in error-marking for scripts sent as AppleEvent parameters. Cmd-dbl-clicking a function call jumps to function, if defined in the same file. 2.1 6/95 - Cmd-dbl-clicking a 'require'd filename opens the file. 2.0 6/95 - Minor bug fixes (incl. keyword decapitalization), and Alpha 6.0b17 compatibility updates. Text Filters folder is settable from the App Paths menu now. 1.9 5/95 - Cmd-dbl-clicking Perl keywords and special variables displays the man page info. 1.8 4/95 - Menu reorganized somewhat. Text Filters folder can now be anywhere. "ApplyToBuffer" flag ignored if text has been selected. 1.7 1/95 - Updated to take advantage of MacPerl 4.1.4 AppleEvent features: 1) Text filters use 'batch' doScript (.: STDOUT file obsolete) 2) Filter scripts sent as doScript params (.: SCRIPT file obsolete) 3) "Save As Droplet" and "Save as Runtime" commands added. Errors generated in 'require'd files are now displayed correctly 1.6 10/94 - "UseDebugger" flag added (forces scripts to run under debugger). Key bindings added for some menu commands. "perlDoScript{,2,3}" procs consolidated into a single proc. "saveAndRun" option added. Command-line args now parsed into units more correctly, in particular, quoted file names aren't broken up. "Close Output Window" added to "Tell MacPerl" menu. Updated for Alpha 5.98 to load when menu is inserted. The error messages window is now recycled. "perlRecycleOutput" recycles output window. Minor bug fixes. 1.5 9/94 - MacPerl menu rearranged somewhat. Explicit "Get Output Window" command added to menu. Reading "#!" line for args is incompatible w/ standard, so it's been dropped. Only scan the first 40 output lines for error messages (faster) "wrapFilterScript" no longer opens STDIN Text filters may now use command-line args STDIN for text filters passed as explicit cmd-line arg 1.4 9/94 - The "#!" line of every script is read for command-line args. "PromptForArgs" menu flag added. "perlCmdlineArgs" modeVar holds default command-line args. Scripts are sent using custom "perlDoScript2" proc. 1.3 9/94 - When any script generates a compilation error, the file containing the script is brought up with the offending line highlighted; all error output is also written to a "Perl Error Messages" window. 'repeatLastFilter' runs again the last text-filter script used. 'perlLastFilter' modeVar holds pathname of last filter. Menu flags now mirrored as modeVars, so they can be saved and restored between sessions. Minor bug fixes. 1.2 8/94 - 'retrieveOutput' and 'autoSwitch' flags added. 'openInMacperl' added. MacPerl output window now closed before new scripts are sent. Filters now abort if there are compilation errors, and MacPerl diagnostic output retrieved and displayed. 1.1 8/94 - 'quitMacperl' added. perl-mode file-marking updated for Alpha 5.90 Simplified installation via 'loadMacperl'(Pete Keleher). 1.0 7/94 - perl-mode setup updated for Alpha 5.85: keyword colorization supported custom file-marking added #! lines in filter scripts now handled correctly Workarounds installed for AppleEvent problem in MacPerl 4.1.3 0.9 3/94 - perl-mode stuff added, and highlighted 'Perl commands' file (man page) prepared minor bug fixes, too 0.8 3/94 - flags are now check-marked 0.7 3/94 - nested Text Filters folder now supported menu format modified somewhat 0.6 3/94 - 'applyToBuffer' flag added scripts in Alpha buffers can now be used as filters 0.5 2/94 - 'filters', 'open special' submenu added 'overwrite' flag added 0.2 1/94 - menu support added by Martijn Koster <m.koster@nexor.co.uk> 'execute selection', 'execute buffer' commands added 0.1 9/93 - text filter functionality created MacPerl application =================== MacPerl was written (ported to the Mac) by Matthias Neeracher <neeri@iis.ee.ethz.ch>, and Tim Endres <time@ice.com>. If you don't already have MacPerl, it's available by anonymous ftp ftp://ftp.switch.ch/software/mac/perl , or ftp://ftp.share.com/pub/macperl More information about MacPerl is available from the MacPerl Q&A page, http://err.ethz.ch/members/neeri/macintosh/perl-qa.html , Hal Wine's official MacPerl FAQ, ftp://ftp.netcom.com/pub/ha/hal/MacPerl/ and Sandra Silcott's MacPerl Primer, http://www.unimelb.edu.au/~ssilcot/macperl-primer/home.html which contains useful hints and sample scripts. ---------------------------------------------------------------------------